package org.iati.mobile;

import java.io.IOException;
import java.util.Map;

import org.iati.mobile.exception.IATIBadFilterException;
import org.iati.mobile.exception.IATIParseXMLException;

/**
 * @author Ionut Dobre
 * @date April 9, 2012
 */

/**
 * IATI API - used to help organizations easily create IATI feeds based on their data sources.
 */

public interface IATI {

	/**
	 * Return list with all donors that are publishing projects. 
	 * The id can be used to retrieve projects that contains this item.
	 * 
	 * @return Map<donorId, donorName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getAllDonors () 
			throws IOException, IATIParseXMLException;

	/**
	 * Return a Map based on IATI identified - Project Name. 
	 * Later method getProjectByIatiIdentifier ($id) can be used in order to retrieve the project details.
	 * 
	 * @return Map<projectId, projectName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getProjectsByDonor (String donorId) 
			throws IOException, IATIParseXMLException;

	/**
	 * Return a list with all sectors used in projects. 
	 * The id can be used to retrieve projects that contains this item.
	 * 
	 * @return Map<sectorId, sectorName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getAllSectors () 
			throws IOException, IATIParseXMLException;

	/**
	 * Return a map based on IATI identified - Project Name. 
	 * Later method getProjectByIatiIdentifier ($id) can be used in order to retrieve the project details
	 * 
	 * @return Map<projectId, projectName>
	 * @throws IATIParseXMLException
	 * @throws IOException 
	 */
	public Map<String, String> getProjectsBySector (String sectorId) 
			throws IATIParseXMLException, IOException;

	/**
	 * Return list with all recipient countries used in projects. 
	 * The id can be used to retrieve projects that contains this item.
	 * 
	 * @return Map<recipientId, countryName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getAllRecipientCountries () 
			throws IOException, IATIParseXMLException;

	/**
	 * Return a map based on IATI identified - Project Name. 
	 * Later method getProjectByIatiIdentifier ($id) can be used in order to retrieve the project details
	 * 
	 * @return Map<projectId, projectName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getProjectsByRecipientCountry (String recipientId) 
			throws IOException, IATIParseXMLException;

	/**
	 * Return list with all reporting organizations used in projects. 
	 * The id can be used to retrieve projects that contains this item.
	 * 
	 * @return Map<reportingOrgId, organizationName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getAllReportingOrganizations () 
			throws IOException, IATIParseXMLException;

	/**
	 * Return a map based on IATI identified - Project Name. 
	 * Later method getProjectByIatiIdentifier ($id) can be used in order to retrieve the project details
	 * 
	 * @return Map<projectId, projectName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getProjectsByReportingOrganization (String reportingOrgId) 
			throws IOException, IATIParseXMLException;

	/**
	 * Return project details.
	 * 
	 * @return IATIProject
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public IATIProject getProjectByIatiIdentifier (String id) 
			throws IOException, IATIParseXMLException;

	/**
	 * Returns the total number of projects.
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public long getNumberOfProjects () 
			throws IOException, IATIParseXMLException;
	
	/**
	 * @param filter specifies the criteria of the query
	 * Return a map based on the criteria specified by the Filter object. 
	 * Later method getProjectByIatiIdentifier ($id) can be used in order to retrieve the project details
	 * 
	 * @return Map<projectId, projectName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String,String> getProjectsByFilter(Filter filter) 
			throws IOException, IATIBadFilterException, IATIParseXMLException;

	/**
	 * @param start - first projectID
	 * @param end - last projectID
	 * 
	 * Return a map based on IATI identified - Project Name. 
	 * Later method getProjectByIatiIdentifier ($id) can be used in order to retrieve the project detail
	 * 
	 * @return Map<projectId, projectName>
	 * @throws IOException 
	 * @throws IATIParseXMLException 
	 */
	public Map<String, String> getAllProjects(long start, long end) 
			throws IOException, IATIParseXMLException;
}
